integrations/react/src/future/loader/loaderPlugin.tsx (1)

109-116: Reuse thenable detection for onBeforePush/onBeforeReplace

Consistently handle thenables here as well.

-    const loaderDataPromise =
-      loaderData instanceof Promise ? loaderData : undefined;
+    const loaderDataPromise =
+      loaderData && typeof (loaderData as any).then === "function"
+        ? (loaderData as Promise<unknown>)
+        : undefined;

.changeset/slick-heads-tan.md (1)

1-6: Clarify API names and options in the changeset

Suggest explicitly listing:

• New action: actions.prepare(activityName[, activityParams])
• New hook: useActivityPreparation(activityNames)
• New option: stackflow({ options: { loaderCacheMaxAge } })
• One-liner on cache semantics and lazy component prefetch.

Improves discoverability for consumers scanning release notes.

integrations/react/src/future/useActivityPreparation.ts (1)

4-4: Consider supporting params to prefetch loader data

Hook currently only preloads components. If loader prefetch requires params, consider an overload or accepting tuples like { name, params }.

Please confirm whether prepare(activityName) without params triggers loader prefetch; if not, the hook name/docs should clarify it only preloads components.

integrations/react/src/__internal__/PluginRenderer.tsx (1)

35-39: Optional: Guard for missing component mapping

Defensive check helps fail fast with a clear message if a mapping is missing at runtime.

-              const Activity = activityComponentMap[activity.name];
+              const Activity = activityComponentMap[activity.name];
+              if (!Activity) {
+                throw new Error(
+                  `No component registered for activity "${activity.name}"`,
+                );
+              }

integrations/react/src/future/lazy.ts (1)

8-12: Nit: Name reflects content (promise vs value)

cachedValue now holds a Promise; consider renaming to cachedPromise for clarity. No functional change.

integrations/react/src/future/stackflow.tsx (1)

102-105: Use referential equality for eviction

Deep comparing whole entries (including data) is unnecessary and slower. The exact object reference can be removed safely.

-        cache.filter((entry) => !isEqual(entry, newCacheEntry)),
+        cache.filter((entry) => entry !== newCacheEntry),

integrations/react/src/future/makeActions.ts (2)

33-33: Reflect async loader in the type of loadData

Actions.prepare wraps loader results in Promise.resolve. Make the type explicit for better DX.

-  loadData: (activityName: string, activityParams: {}) => unknown,
+  loadData: (activityName: string, activityParams: {}) => unknown | Promise<unknown>,

---

110-114: Narrow to LazyActivityComponentType before calling _load for stronger type safety

This avoids property access on a broad component type and prevents TS errors under stricter configs.

-      if ("_load" in activityComponentMap[activityName]) {
-        const lazyComponent = activityComponentMap[activityName];
-
-        prefetchTasks.push(Promise.resolve(lazyComponent._load?.()));
-      }
+      if ("_load" in activityComponentMap[activityName]) {
+        const lazyComponent =
+          activityComponentMap[activityName] as LazyActivityComponentType<any>;
+        prefetchTasks.push(Promise.resolve(lazyComponent._load?.()));
+      }

integrations/react/src/future/loader/loaderPlugin.tsx (1)

109-110: Minor: skip calling loadData when the activity has no loader

Avoids unnecessary cache entries/timers when no loader exists.

-    const loaderData = loadData(activityName, activityParams);
+    const loaderData = matchActivity.loader
+      ? loadData(activityName, activityParams)
+      : undefined;

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

integrations/react/src/__internal__/MainRenderer.tsx (1)

2-2: Remove obsolete activityComponentMap prop and unused import

The component no longer consumes activityComponentMap. Clean up the prop type and import to avoid confusion and unused types.

-import type { ActivityComponentType } from "./ActivityComponentType";
@@
-interface MainRendererProps {
-  activityComponentMap: {
-    [key: string]: ActivityComponentType;
-  };
-  initialContext: any;
-}
+interface MainRendererProps {
+  initialContext: any;
+}

Also applies to: 9-15

integrations/react/src/future/makeActions.ts (1)

50-63: replace() returns an ID that may not match the one used in the core action

You compute activityId but call replace() with a different ID. This breaks consumer expectations and tracking.

-    replace(activityName, activityParams, options) {
-      const activityId = makeActivityId();
+    replace(activityName, activityParams, options) {
+      const activityId = options?.activityId ?? makeActivityId();
@@
-      getCoreActions()?.replace({
-        activityId: options?.activityId ?? makeActivityId(),
+      getCoreActions()?.replace({
+        activityId,
         activityName,
         activityParams,
         skipEnterActiveState: parseActionOptions(options).skipActiveState,
       });

integrations/react/src/future/loader/loaderPlugin.tsx (1)

90-113: Avoid unnecessary loadData calls and handle sync throws in route handler

Only call loadData if a loader exists, and normalize sync throws to a rejected promise for consistent pause/resume behavior.

-  input: StackflowInput<T, R>,
-  loadData: (activityName: string, activityParams: {}) => unknown,
+  input: StackflowInput<T, R>,
+  loadData: (activityName: string, activityParams: {}) => unknown,
 ): OnBeforeRoute {
@@
-    const loaderData = loadData(activityName, activityParams);
-
-    const loaderDataPromise =
-      loaderData instanceof Promise ? loaderData : undefined;
+    let loaderData: unknown | undefined;
+    if (matchActivity.loader) {
+      try {
+        loaderData = loadData(activityName, activityParams);
+      } catch (err) {
+        loaderData = Promise.reject(err);
+      }
+    }
+    const loaderDataPromise =
+      loaderData instanceof Promise ? loaderData : undefined;

integrations/react/src/future/useFlow.ts (1)

14-22: Stabilize Actions object with useMemo

makeActions(...) is executed on every render, changing the Actions object identity and potentially causing unnecessary re-renders. Memoize based on inputs.

+import { useMemo } from "react";
@@
-  const actions = makeActions(
-    config,
-    () => coreActions,
-    activityComponentMap,
-    loadData,
-  );
-
-  return actions;
+  const actions = useMemo(
+    () =>
+      makeActions(
+        config,
+        () => coreActions,
+        activityComponentMap,
+        loadData,
+      ),
+    [config, coreActions, activityComponentMap, loadData],
+  );
+
+  return actions;

integrations/react/src/future/ActivityComponentMapProvider.tsx (1)

1-38: Solid context API; minor type-hardening optional

Implementation looks correct and aligns with the new access pattern. Optionally mark the map as readonly to prevent accidental mutation.

-const ActivityComponentMapContext = createContext<
-  | {
-      [activityName in RegisteredActivityName]: ActivityComponentType;
-    }
-  | null
->(null);
+const ActivityComponentMapContext = createContext<
+  | Readonly<Record<RegisteredActivityName, ActivityComponentType>>
+  | null
+>(null);
@@
-type ActivityComponentMapProviderProps = PropsWithChildren<{
-  value: {
-    [activityName in RegisteredActivityName]: ActivityComponentType;
-  };
-}>;
+type ActivityComponentMapProviderProps = PropsWithChildren<{
+  value: Readonly<Record<RegisteredActivityName, ActivityComponentType>>;
+}>;

integrations/react/src/__internal__/MainRenderer.tsx (1)

15-15: Optional: Narrow any

If feasible, narrow initialContext: any to a more specific type or unknown to reduce implicit-any usage.

-const MainRenderer: React.FC<MainRendererProps> = ({ initialContext }) => {
+const MainRenderer: React.FC<MainRendererProps> = ({ initialContext }) => {

(Consider updating MainRendererProps.initialContext to unknown or a concrete type.)

integrations/react/src/future/loader/DataLoaderContext.tsx (1)

3-5: Unify and reuse the loader function type via a named alias

Define a DataLoaderFn type and reuse it here to reduce duplication and keep signatures consistent across modules.

Apply:

 export const DataLoaderContext = createContext<
-  ((activityName: string, activityParams: {}) => unknown) | null
+  DataLoaderFn | null
 >(null);
@@
 }: {
-  loadData: (activityName: string, activityParams: {}) => unknown;
+  loadData: DataLoaderFn;
   children: ReactNode;
 })

Add near the top (outside the selected range):

export type DataLoaderFn = (activityName: string, activityParams: {}) => unknown;

Also applies to: 11-13

integrations/react/src/future/makeActions.ts (1)

110-114: Type-narrow lazy components before calling _load

Use a type guard (or cast) so TS understands _load exists on lazy components.

-      if ("_load" in activityComponentMap[activityName]) {
-        const lazyComponent = activityComponentMap[activityName];
-
-        prefetchTasks.push(Promise.resolve(lazyComponent._load?.()));
-      }
+      if ("_load" in activityComponentMap[activityName]) {
+        const lazyComponent =
+          activityComponentMap[activityName] as LazyActivityComponentType<any>;
+        prefetchTasks.push(Promise.resolve(lazyComponent._load?.()));
+      }

If preferred, add a type guard outside the selected range and use it:

function isLazyActivityComponent(
  c: ActivityComponentType<any>,
): c is LazyActivityComponentType<any> {
  return typeof (c as any)._load === "function";
}

integrations/react/src/future/stackflow.tsx (1)

70-73: Consider refreshing TTL on cache hits (sliding expiration)

Returning a cached value does not extend its lifetime. If desired UX is “keep warm while accessed,” refresh expiry when a hit occurs.

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

integrations/react/src/future/stackflow.tsx (1)

63-109: Don't cache when there's no loader; evict on rejected loader promises; clean up empty buckets

Currently, activities without a loader are cached with data: undefined, and rejected Promises remain cached until TTL. This causes unnecessary cache entries and prevents retries after failures within the TTL window.

   const loadData = (activityName: string, activityParams: {}) => {
@@
-    const loaderData = activityConfig.loader?.({
-      params: activityParams,
-      config: input.config,
-    });
+    if (!activityConfig.loader) {
+      // No loader for this activity: don't cache undefined
+      return undefined;
+    }
+
+    const loaderData = activityConfig.loader({
+      params: activityParams,
+      config: input.config,
+    });
     const newCacheEntry = {
       params: activityParams,
       data: loaderData,
     };
 
     if (cache) {
       cache.push(newCacheEntry);
     } else {
       loaderDataCacheMap.set(activityName, [newCacheEntry]);
     }
 
+    // If the loader rejects, evict this entry immediately to allow retrial
+    if (loaderData instanceof Promise) {
+      loaderData.catch(() => {
+        const cache = loaderDataCacheMap.get(activityName);
+        if (!cache) return;
+        const next = cache.filter((entry) => entry !== newCacheEntry);
+        if (next.length > 0) {
+          loaderDataCacheMap.set(activityName, next);
+        } else {
+          loaderDataCacheMap.delete(activityName);
+        }
+      });
+    }
+
     setTimeout(() => {
       const cache = loaderDataCacheMap.get(activityName);
 
       if (!cache) return;
 
-      loaderDataCacheMap.set(
-        activityName,
-        cache.filter((entry) => entry !== newCacheEntry),
-      );
+      const next = cache.filter((entry) => entry !== newCacheEntry);
+      if (next.length > 0) {
+        loaderDataCacheMap.set(activityName, next);
+      } else {
+        loaderDataCacheMap.delete(activityName);
+      }
     }, input.options?.loaderCacheMaxAge ?? DEFAULT_LOADER_CACHE_MAX_AGE);

integrations/react/src/future/makeActions.ts (2)

5-17: Simplify parseActionOptions; reduce branches while preserving semantics

Current logic returns the same result using multiple early returns. This can be simplified and made more readable.

Apply this diff:

-function parseActionOptions(options?: { animate?: boolean }) {
-	if (!options) {
-		return { skipActiveState: false };
-	}
-
-	const isNullableAnimateOption = options.animate == null;
-
-	if (isNullableAnimateOption) {
-		return { skipActiveState: false };
-	}
-
-	return { skipActiveState: !options.animate };
-}
+function parseActionOptions(options?: { animate?: boolean }) {
+  const animate = options?.animate;
+  // Skip transitions only when animate is explicitly false; otherwise don't skip.
+  return { skipActiveState: animate === false };
+}

---

49-77: Avoid recomputing parseActionOptions inside the loop

Minor readability/perf nit: compute the first-skip value once outside the loop.

Apply this diff:

       if (options) {
         _options = {
           ...options,
         };
       }

-      for (let i = 0; i < _count; i += 1) {
-        getCoreActions()?.pop({
-          skipExitActiveState:
-            i === 0 ? parseActionOptions(_options).skipActiveState : true,
-        });
-      }
+      const skipFirstExit = parseActionOptions(_options).skipActiveState;
+      for (let i = 0; i < _count; i += 1) {
+        getCoreActions()?.pop({
+          skipExitActiveState: i === 0 ? skipFirstExit : true,
+        });
+      }

integrations/react/src/future/usePrepare.ts (1)

11-16: Stabilize the returned function identity with useCallback

Small ergonomics improvement: memoize the returned prepare to avoid referential changes across re-renders.

-export function usePrepare(): Prepare {
-  const config = useConfig();
-  const loadData = useDataLoader();
-  const activityComponentMap = useActivityComponentMap();
-
-  return async function prepare<K extends RegisteredActivityName>(
+export function usePrepare(): Prepare {
+  const config = useConfig();
+  const loadData = useDataLoader();
+  const activityComponentMap = useActivityComponentMap();
+
+  const prepare = useCallback(
+    async function prepare<K extends RegisteredActivityName>(

Outside this hunk, add the import:

import { useCallback } from "react";

And at the end of the function return the memoized callback:

  }, [config, loadData, activityComponentMap]);

  return prepare;

integrations/react/src/future/stackflow.tsx (1)

44-46: Configurable cache TTL is a solid choice

options.loaderCacheMaxAge adds needed flexibility. Consider documenting units (ms) in JSDoc for clarity.

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

integrations/react/src/__internal__/utils/isPromiseLike.ts (2)

2-7: Broaden thenable detection to include callable thenables (Promises/A+).

Promises/A+ defines a thenable as an object or function with a then method. Current check excludes callable thenables. This is a defensive improvement and avoids rare false negatives.

Apply this diff:

 export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return (
-    typeof value === "object" &&
+    (typeof value === "object" || typeof value === "function") &&
     value !== null &&
     "then" in value &&
-    typeof value.then === "function"
+    typeof (value as { then: unknown }).then === "function"
   );
 }

---

1-8: Add a brief JSDoc for clarity and future maintainability.

This utility will be widely used in loader handling; documenting the intended semantics (thenable detection) helps avoid misuses and regressions.

+/**
+ * Returns true if the given value is a thenable (Promise-like): an object or function
+ * with a `then` method. Useful when a loader may return either a value or a promise.
+ */
 export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return (
     (typeof value === "object" || typeof value === "function") &&
     value !== null &&
     "then" in value &&
     typeof (value as { then: unknown }).then === "function"
   );
 }

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

integrations/react/src/future/stackflow.tsx (2)

79-86: Skip caching when an activity has no loader

Caching an entry with undefined data for activities without a loader causes unnecessary memory usage and timers. Return early instead. This mirrors earlier feedback.

-    const loaderData = activityConfig.loader?.({
-      params: activityParams,
-      config: input.config,
-    });
+    if (!activityConfig.loader) {
+      // No loader for this activity: don't cache undefined
+      return undefined;
+    }
+
+    const loaderData = activityConfig.loader({
+      params: activityParams,
+      config: input.config,
+    });

Also applies to: 88-93

---

99-103: Delete the map entry when the cache bucket becomes empty

Avoid retaining empty arrays in the map to reduce memory footprint and keep the structure clean. This also aligns with prior feedback to evict by reference and cleanly remove buckets.

-      loaderDataCacheMap.set(
-        activityName,
-        cache.filter((entry) => entry !== newCacheEntry),
-      );
+      const next = cache.filter((entry) => entry !== newCacheEntry);
+      if (next.length > 0) {
+        loaderDataCacheMap.set(activityName, next);
+      } else {
+        loaderDataCacheMap.delete(activityName);
+      }

config/src/ActivityLoader.ts (1)

4-7: Tighten the type surface: mark TTL as readonly; consider generics over the return type

• Marking loaderCacheMaxAge as readonly communicates intent and prevents accidental mutation elsewhere.
• Consider making the return type generic (e.g., <TData = unknown>) instead of any to improve type-safety end-to-end.

-export type ActivityLoader<ActivityName extends RegisteredActivityName> = {
-  (args: ActivityLoaderArgs<ActivityName>): any;
-  loaderCacheMaxAge?: number;
-};
+export type ActivityLoader<ActivityName extends RegisteredActivityName, TData = unknown> = {
+  (args: ActivityLoaderArgs<ActivityName>): TData;
+  readonly loaderCacheMaxAge?: number;
+};

Note: If you adopt the generic return type here, propagate it through call sites where ActivityLoader is referenced.

integrations/react/src/future/stackflow.tsx (1)

60-62: Narrow the types for loader cache keys and params

Using RegisteredActivityName and ActivityBaseParams improves type safety across the stack and matches the config types.

-  const loaderDataCacheMap = new Map<string, { params: {}; data: unknown }[]>();
-  const loadData = (activityName: string, activityParams: {}) => {
+  const loaderDataCacheMap = new Map<
+    RegisteredActivityName,
+    { params: ActivityBaseParams; data: unknown }[]
+  >();
+  const loadData = (
+    activityName: RegisteredActivityName,
+    activityParams: ActivityBaseParams,
+  ) => {

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

integrations/react/src/future/useActivityPreparation.ts (1)

5-11: Optionally accept activityParams and avoid floating Promises

Since prepare supports (activityName[, activityParams]), you can pass through optional params now and explicitly discard the returned Promise to appease “no-floating-promises” linters. Also consider a readonly array to discourage mutation.

Apply:

 export function useActivityPreparation(
-  activities: { activityName: RegisteredActivityName }[],
-) {
+  activities: ReadonlyArray<{
+    activityName: RegisteredActivityName;
+    activityParams?: unknown;
+  }>,
+): void {
   const prepare = usePrepare();

-  for (const { activityName } of activities) {
-    prepare(activityName);
+  for (const { activityName, activityParams } of activities) {
+    void prepare(activityName, activityParams);
   }
 }

Notes:

• If you prefer stronger typing for activityParams, we can introduce a mapped type later without breaking callers.

.changeset/slick-heads-tan.md (1)

5-7: Tighten wording and include cache TTL detail

Minor grammar/style fixes and add the default cache TTL + configuration knob to make the release notes more actionable.

-Add prefetch API for lazy activity component and loader data.
-- A hook `usePrepare()` which returns `prepare(activityName[, activityParams])` is added for navigation warmup.
-- A hook `useActivityPreparation(activities)` for preparing navigations inside a component is added.
+Add a prefetch API for lazy activity components and their loader data.
+- New: `usePrepare()` returns `prepare(activityName[, activityParams])` for navigation warm-up.
+- New: `useActivityPreparation(activities)` prepares navigations inside a component. Each item is `{ activityName }`.
+- Preloaded loader data is cached for 30 seconds by default; configure the max age via `options.loaderCacheMaxAge`.

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.